primefaces/datatable.md at master · primefaces/primefaces · GitHub

DataTable displays data in tabular format.

See this widget in the JavaScript API Docs.

We will be using the same Car and CarBean classes described in DataGrid section. Here is the simplest way to get started:

In case no children are present in columns, value from var and field will be displayed.

Both datatable itself and columns can have custom content in their headers and footers using header and footer facets respectively. Alternatively for columns there are headerText and footerText shortcuts to display simple texts.

DataTable has a built-in ajax based paginator that is enabled by setting paginator option to true, see pagination section in dataGrid documentation for more information about customization options.

Optionally enabling clientCache property loads the next page asynchronously so that when user clicks the second page, data is displayed instantly from client side.

Paginator is customized using paginatorTemplate attribute accepting various keys of UI controls.

Note that {RowsPerPageDropdown} has its own template, options to display is provided via rowsPerPageTemplate attribute (e.g. rowsPerPageTemplate="9,12,15").

Also {CurrentPageReport} has it's own template defined with currentPageReportTemplate option. You can use {currentPage},{totalPages},{totalRecords},{startRecord},{endRecord} keyword within currentPageReportTemplate. Default is "{currentPage} of {totalPages}". Default UI is:

which corresponds to the following template.

Here are more examples based on different templates;

{CurrentPageReport} {FirstPageLink} {PreviousPageLink} {PageLinks} {NextPageLink} {LastPageLink} {RowsPerPageDropdown}

{PreviousPageLink} {CurrentPageReport} {NextPageLink}

Paginator can be positoned using paginatorPosition attribute in three different locations, "top", "bottom" or "both" (default).

Custom content can be placed inside a paginator using a facet name matching a token in the template.

Defining field or sortBy attribute enables ajax based sorting on that particular column. Sorting cycles through ascending, descending and unsorted upon clicking on the column header.

Instead of using the default sorting algorithm which uses a java comparator, you can plug-in your own sort method as well.

Multiple sorting is enabled by default. In this mode, clicking a sort column while metakey is on adds sort column to the order group. Change attribute sortMode to single to allow only one column.

DataTable can display data sorted by default, by either setting default attributes on p:column or using sortBy attribute of datatable. Table below would be initially displayed as sorted by model.

Or

Ajax based filtering is enabled by setting field or filterBy at column level and providing a list to keep the filtered sublist. It is suggested to use a scope longer than request like viewscope to keep the filteredValue so that filtered list is still accessible after filtering. (Attention: Please be aware sessionscope is not supported for this. Instead set multiViewState="true" to keep table state including filter across views.)

Filtering is triggered with keyup event and filter inputs can be styled using filterStyle , filterStyleClass attributes. If you’d like to use a dropdown instead of an input field to only allow predefined filter values use filterOptions attribute and a collection/array of selectitems as value. In addition, filterMatchMode defines the built-in matcher which is startsWith by default.

Following is a basic filtering datatable with these options demonstrated:

Filter located at header is a global one applying on all fields, this is implemented by calling client side API method called filter(), important part is to specify the id of the input text as globalFilter which is a reserved identifier for datatable.

In addition to default filtering with generated elements, custom elements can also be used as a filter facet. Example below uses custom filter components in combination with generated elements. When a custom component is used as a filter facet, filtering needs to be called manually from a preferred event such as onchange="PF('carsTable').filter()". Also defining a converter might be necessary if the value of the filter facet is not defined.

Please make sure that the filter is using the same type as the column field if you are using comparable filter match modes (like greater than). For example, if the column field is an integer, and you would like to add a greater than filter, make sure to convert the filter to integer as well. Do so by adding a f:converter (see example below).

filterMatchMode defines which built-in filtering algorithm would be used per column, valid values for this attribute are;

In case the built-in methods do not suffice, custom filtering can be implemented using filterFunction approach.

filterFunction should be a method with three parameters; column value, filter value and locale. Return value is a boolean, true accepts the value and false rejects it.

Locale is provided as optional in case you need to use a locale aware method like toLowerCase(Locale locale). Note that | String | based filters like startsWith, endsWith uses toLowerCase already and dataLocale attribute is used to provide the locale to use when filtering.

This same principle can be applied globally by implementing a globalFilterFunction. It takes the same parameters of which the first parameter is the row value.

Default filtering can be set up with markup or programmatically. Here is two ways to go about it:

Or using DataTable#filterBy and FilterMeta#builder:

There are several ways to select row(s) from datatable. Let’s begin by adding a Car reference for single selection and a Car array for multiple selection to the CarBean to hold the selected data.

This method is implemented with a command component such as commandLink or commandButton. Selected row can be set to a server side instance by passing as a parameter if you are using EL 2.2 or using f:setPropertyActionListener.

Previous method works when the button is clicked, if you’d like to enable selection wherever the row is clicked, use selectionMode option.

Multiple row selection is similar to single selection but selection should reference an array or a list of the domain object displayed and user needs to use press modifier key(e.g. ctrl) during selection *.

Selection a row with a radio button placed on each row is a common case, datatable has built-in support for this method so that you don’t need to deal with h:selectOneRadios and low level bits. In order to enable this feature, define a column with selectionMode set as single.

Similar to how radio buttons are enabled, define a selection column with a multiple selectionMode. DataTable will also provide a selectAll checkbox at column header.

Tip: Use rowSelectMode option to customize the default behavior on row click of a multiple selection enabled datatable. Default value is "new" that clears previous selections, "add" mode keeps previous selections same as selecting a row with mouse click when metakey is on and "checkbox" mode allows row selection with checkboxes only.

RowKey should a unique identifier from your data model and used by datatable to find the selected rows. You must define this key by using the rowKey attribute.

!> RowKey must not contain a comma , as it will break row selection. See GitHub #8932.

Dynamic columns is handy in case you can’t know how many columns to render. Columns component is used to define the columns programmatically. It requires a collection as the value, two iterator variables called var and columnIndexVar.

Grouping is defined by ColumnGroup component used to combine datatable header and footers.

For frozen columns, use frozenHeader , frozenFooter , scrollableHeader and scrollableFooter types.

Rows can be grouped in two ways, using headerRow, summaryRow components or with groupRow attribute on a column.

!> Row Grouping does not work with Lazy Loading and LiveScroll as the grouping needs to know about all rows to properly group the rows.

Optionally rows can be made toggleable using HeaderRow#expandable property.

Alternative approach is using row spans where a row can group multiple rows within the same group. To enable this method, set groupRow to true on the grouping column.

Scrolling makes the header-footer of the table fixed and the body part scrollable. Scrolling is enabled using scrollable property and has 3 modes; x, y and x-y scrolling that are defined by scrollHeight and scrollWidth. These two scroll attributes can be specified using integer values indicating fixed pixels or percentages relative to the container dimensions.

Simple scrolling renders all data to client whereas virtual scrolling combined with lazy loading is useful to deal with huge data, in this case data is fetched on-demand. Set virtualScroll to enable this option and provide LazyDataModel;

Certain rows can be fixed in a scrollable table by using the frozenRows attribute that defines the number of rows to freeze from the start.

Specific columns can be fixed while the rest of them remain as scrollable. frozenColumns defines the number of columns to freeze from the start.

RowToggler and RowExpansion facets are used to implement expandable rows.

p:rowToggler component places an expand/collapse icon, clicking on a collapsed row loads expanded content with ajax. If you need to display a row as expanded by default, use expandedRow attribute which is evaluated before rendering of each row so value expressions are supported. Additionally, rowExpandMode attribute defines if multiple rows can be expanded at the same time or not, valid values are "single" and "multiple" (default).

Incell editing provides an easy way to display editable data. p:cellEditor is used to define the cell editor of a particular column. There are two types of editing, row and cell. Row editing is the default mode and used by adding a p:rowEditor component as row controls.

When pencil icon is clicked, row is displayed in editable mode meaning input facets are displayed and output facets are hidden. Clicking tick icon only saves that particular row and cancel icon reverts the changes, both options are implemented with ajax interaction.

Another option for incell editing is cell editing, in this mode a cell switches to edit mode when it is clicked, losing focus triggers an ajax event to save the change value.

Lazy Loading is an approach to deal with huge datasets efficiently, regular AJAX based pagination works by rendering only a particular page but still requires all data to be loaded into memory. Lazy loading DataTable renders a particular page similarly but also only loads the page data into memory not the whole dataset. In order to implement this, you’d need to bind a org.primefaces.model.LazyDataModel as the value and implement load and count method. If you have selection enabled, you either need to implement getRowData and getRowKey, or pass a existing JSF Converter to the constructor.

DataTable calls your load implementation whenever a paging, sorting or filtering occurs with following parameters:

In addition to load method, count method needs to be implemented, so that paginator can display itself according to the logical number of rows to display.

It is suggested to use field attribute of column component to define the field names passed as sortBy and filterBy, otherwise these fields would be tried to get extracted from the value expression which is not possible in cases like composite components.

To avoid doing a separate count-statement against your datasource you may implement it like this: (This may help to improve performance but comes at the price of keeping an eye on #1921.)

A third variant may be doing something like this:

PrimeFaces provides a OOTB implementation for JPA users, which supports basic features.

If you have selection enabled, you can either pass the rowKey field name in the constructor:

or provide a existing JSF Converter:

Also you can add global filters via: